home *** CD-ROM | disk | FTP | other *** search
/ Aminet 15 / Aminet 15 - Nov 1996.iso / Aminet / comm / mail / YamNet.lha / rexxtra12.lha / RexxExtra.doc next >
Text File  |  1990-04-29  |  16KB  |  480 lines
  1.  
  2.  
  3.                   RexxExtra
  4.                   ---------
  5.  
  6.       Documentation on the rexxextra.library (Version 1.2)
  7.  
  8.               Date: March 18, 1990
  9.  
  10.  
  11.   Introduction
  12.   ------------
  13.  
  14.     rexxextra.library is an ARexx external function library. It's
  15.     purpose is to extend the string manipulation and mathematical
  16.     capabilities of ARexx by defining new functions.
  17.  
  18.     This library is intended for users of ARexx, the Amiga
  19.     implementation of the high level language by William S. Hawes,
  20.     who wish to expand the set of functions available, just as the
  21.     libraries supplied with ARexx (rexxsupport, rexxarplib, and
  22.     rexxmathlib.library) add new functions.
  23.  
  24.   Archive Contents
  25.   ----------------
  26.  
  27.     The following files should be contained in this archive file.
  28.  
  29.       File          Size      Description
  30.       -----------------  -----      -----------
  31.  
  32.       rexxextra.library   7060      The ARexx library. Copy to libs:
  33.       RexxExtra.doc     16226      This file. This size may vary some.
  34.       Test.rexx       3946      Exercises and verifies the library
  35.                   functions
  36.       rexx/ directory     37960      Example programs (approx.)
  37.  
  38.     Please distribute the library archive only in it's original
  39.     form, without changes or additions. If possible, when uploading
  40.     to a BBS, name the archive RXXTRA12.LZH so we may all know
  41.     which version it is.
  42.  
  43.     Although WShell (also by Mr. Hawes), an Amiga command shell, is
  44.     not needed to use RexxExtra, all example programs have only
  45.     been run under WShell, so these may have to be modified to run
  46.     under your own shell. Probably by adding "address command" in
  47.     front of any CLI callable command strings.
  48.  
  49.  
  50.   Installation
  51.   ------------
  52.  
  53.     First, copy the included rexxextra.library file to your libs:
  54.     directory. The size is only about 7K.
  55.  
  56.        copy rexxextra.library libs:
  57.  
  58.   Adding the library to ARexx
  59.   ---------------------------
  60.  
  61.     The functions are available to any ARexx program once the
  62.     command:
  63.  
  64.        call addlib 'rexxextra.library',-20,-30,0
  65.  
  66.     has been issued in any Arexx program. This only need be done
  67.     once per session (I do all mine at bootup, then I don't have
  68.     to worry about it). The included ARexx programs contains this
  69.     step.
  70.  
  71.  
  72.   Description of library functions
  73.   --------------------------------
  74.  
  75.     Basically, you've now got some new functions available you can
  76.     call from any ARexx program. More are being added, so this list
  77.     will grow in the future.
  78.  
  79.  
  80.       o Replace()   - replace one string with another throughout a
  81.               third.
  82.  
  83.       o Sortwords() - sorts string of words into alphabetical order.
  84.  
  85.       o Cparse()    - "parse" a command line.
  86.  
  87.       o Fparse()    - "parse" a file name.
  88.  
  89.  
  90.     You also have some example ARexx programs using and testing
  91.     these functions.
  92.  
  93.     Following is a detailed description of each of the functions.
  94.  
  95.  
  96.   =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  97.  
  98.   Replace - replace one string with another in a string
  99.   -------
  100.  
  101.     Syntax
  102.     ======
  103.  
  104.     string4 = Replace(string1,string2,string3,['Case'])
  105.  
  106.     string1 is the string to replace with.
  107.  
  108.     string2 is the string to look for.
  109.  
  110.     string3 is string to perform replacment on.
  111.  
  112.     'Case' is an optional argument and, if supplied, case will be
  113.     ignored when searching for string2 in string3.
  114.  
  115.     string4 is returned value when all string2's have been replaced
  116.     by string1's in string3.
  117.  
  118.     Description
  119.     ===========
  120.  
  121.     This function was the first one I tried the library out with,
  122.     and its such a simple and useful function, I decided to leave
  123.     it in.
  124.  
  125.     Restrictions
  126.     ============
  127.  
  128.     The result string cannot be longer than 10 times string3. If
  129.     anybody knows of a good way to compute the length needed for
  130.     the result string before doing the replace, let me know.
  131.  
  132.  
  133.   =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  134.  
  135.   Sortwords - sort a string of words
  136.   ---------
  137.  
  138.     Syntax
  139.     ======
  140.  
  141.     string2 = SortWords(string1)
  142.  
  143.     string1 is list of words to sort
  144.  
  145.     string2 is sorted string1
  146.  
  147.     Description
  148.     ===========
  149.  
  150.     This function will returns its argument, which is a string of
  151.     words, into ascending alphabetical order. Currently, the space
  152.     is the only delimiter for words.
  153.  
  154.     As with ARexx itself, string1 and the returned string are
  155.     limited to about 65,500 characters.
  156.  
  157.   =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  158.  
  159.   Cparse - parse a command line
  160.   ------
  161.  
  162.     Syntax
  163.     ======
  164.  
  165.     string = Cparse(commandline,template,stem)
  166.  
  167.  
  168.     commandline is as recieved from the user, ie, "parse arg
  169.     commandline".
  170.  
  171.     template is standard AmigaDOS/ARP command template (with
  172.     extensions), ie, "Q=QUICK/S,BUF=BUFFER/K,FROM,TO/A". Note: Any
  173.     single keyword should not be more than 30 characters.
  174.  
  175.     stem is the name of the stem variable to use for the compound
  176.     variables to create. You might want to keep this relatively
  177.     short, especially if you're getting many arguments from the
  178.     command line. You do not need to include the ending period.
  179.  
  180.     Description
  181.     ===========
  182.  
  183.     This function allows you to quickly and easily determine the
  184.     input to your ARexx program, and "parse" the command line into
  185.     a whole set of user-defined variables. This gives your ARexx
  186.     programs the power of AmigaDOS/ARP command parsing with one
  187.     function call.
  188.  
  189.     You supply to the function in a standard AmigaDOS/ARP template
  190.     format (with certain extensions) what to expect on the command
  191.     line. The function scans the command line, determining what
  192.     flags, arguments, qualifiers and such are present, and returns
  193.     a "program string" (a string suitable for INTERPRETing)
  194.     containing the commands neccessary to assign values from the
  195.     command line to variables in the program. Got that? Well,
  196.     fortunately using Cparse is simpler than explaining it.
  197.  
  198.     For instance, we want to write an ARexx program that accepts
  199.     the same arguments as the LIST command. Let's call it TREE. The
  200.     TREE command has a template of:
  201.  
  202.       DIR,P=PAT/K,KEYS/S,DIRS/S,FILES/S,SORT/S,SINCE/K,UPTO/K,
  203.       DATES/S,NODATES/S,SUB/K,BLOCK=BLOCKS/S,NOHEAD/S,LFORMAT/K
  204.  
  205.     This function will fill in args.DIR, args.P, args.KEYS,
  206.     args.DIRS, etc. from the supplied command line. Arguments,
  207.     qualifiers, and flags may appear on the command line in any
  208.     order, just as with AmigaDOS/ARP. Command lines are verified
  209.     for missing arguments, and a variable is assigned a severity
  210.     level (0...2) so you can determine the the error, if any.
  211.  
  212.     You must format the template in this order: flags (/S),
  213.     qualifiers (/K), arguments (/A & /R) and optional arguments
  214.     (in the order to expect them from the user), then lists (/...
  215.     & /L). For example, the TREE command would pass a template of:
  216.  
  217.       KEYS/S,DIRS/S,FILES/S,SORT/S,DATES/S,NODATES/S,BLOCK=BLOCKS/S,
  218.       NOHEAD/S,SINCE/K,UPTO/K,P=PAT/K,SUB/K,LFORMAT/K,DIR
  219.  
  220.     You must also decide on a stem variable name before calling
  221.     this routine. You may assign values to the compound variables
  222.     for default responses (except switches); these will not be
  223.     changed if that option is missing from the command line.
  224.     Switches will always be in the returned string, and will always
  225.     be a boolean value.
  226.  
  227.     Synonyms for keywords (those following an "=" in the template)
  228.     are supported, but the assigned variable will always be the
  229.     keyword on the LEFT of the equals sign.
  230.  
  231.     If, after resolving all template tokens, there is still some
  232.     commandline left, a variable "stem.REMAIN" is added equaling
  233.     what's left. Consequently, you may find it difficult to use
  234.     "REMAIN" as a keyword in your template.
  235.  
  236.     A variable, "stem.ERRCODE" is added indicating if any errors
  237.     were encountered while parsing the commandline. If errors are
  238.     encountered, another variable "stem.ERRTEXT" is also added to
  239.     explain the error. Consequently, you may find it difficult to
  240.     use "ERRCODE" and "ERRTEXT" as keywords in your template.
  241.  
  242.     Either single or double quotes are recognized for delimiting an
  243.     argument containing spaces. However, the "double quoting"
  244.     convention (two quotes in a row to denote one in the string) is
  245.     not accepted.
  246.  
  247.     In summary,
  248.  
  249.       token       variable        description
  250.       -----       --------        -----------
  251.       FLAG/S       stem.FLAG        1 if present, 0 if not.
  252.       QUALIFIER/K  stem.QUALIFIER   value of following string
  253.                     or not changed if not present.
  254.       ARGUMENT/A   stem.ARGUMENT    value of following string if
  255.                     keyword present, first string found
  256.                     after removing flags and qualifiers
  257.                     if not.
  258.       ARGUMENT/R            same as /A but keyword is required
  259.       ARGUMENT       stem.ARGUMENT    value of first string found
  260.                     after removing flags and qualifiers
  261.       LIST/...       stem.LIST.0        count of items in list. 0 if none.
  262.            stem.LIST.1        list items
  263.               thru
  264.            stem.LIST.n
  265.       LIST/L                same as /... but list is required.
  266.            stem.REMAIN        remainder of command line after all
  267.                     tokens have been parsed out
  268.            stem.ERRCODE     0 if no errors parsing commandline
  269.                     1 if remainder but no other problems
  270.                     2 if required argument missing or
  271.                       qualifier keyword specified w/o
  272.                       value
  273.            stem.ERRTEXT     explanation of error (currently if > 1)
  274.  
  275.     Note: The AmigaDOS tempate structure of multiple commas
  276.       (",,,,,,,") is not supported.
  277.  
  278.  
  279.     Using Cparse
  280.     ============
  281.  
  282.     There are probably many ways Cparse could be used, but here's what
  283.     I do. This adds complete interactive command line parsing to any
  284.     ARexx program. In each ARexx program I want to add command parsing
  285.     capabilities to, I start with or add this "template" and modify to
  286.     suit.
  287.  
  288.     This template contains statements to do the preliminary work for
  289.     Cparse, such as handling "?" on the command line, presenting a
  290.     template to the user, showing additional help upon entry of a
  291.     second "?", calling the Cparse function, and exiting if an invalid
  292.     command line is found.
  293.  
  294.     The user may request additional help by entering a second "?" at
  295.     the display of the template. The program will display help
  296.     information contained in the source code of the program. Place
  297.     this "self-documenting" help using a comment in the ARexx
  298.     program. The beginning of the comment must be the third source
  299.     line, and continues until a close comment is found.
  300.  
  301.       ---------------------------------------------------------------
  302.       /* typical.rexx */
  303.  
  304.       /*
  305.       Typical ARexx program using Command Line Parsing
  306.             and help system
  307.  
  308.       USAGE: TYPICAL [FROM] <file> [TO <dir>] [QUIET]
  309.       */
  310.       dtemplate = 'FROM/A,TO/K,QUIET/S' /* template displayed to the user */
  311.       template    = 'QUIET/S,FROM/A,TO/K' /* template supplied to Cparse    */
  312.       args.=''                          /* stem variable to use           */
  313.  
  314.       parse arg g_c
  315.       do while g_c='?'
  316.     options prompt dtemplate
  317.     parse pull g_c
  318.     if g_c='?' then do
  319.       g_s=sourceline(3)
  320.       if pos('/*',g_s)=0 then break; if pos('*/',g_s)>0 then break
  321.       say
  322.       g_s=sourceline(4)
  323.       do i=5 while pos('*/',g_s)=0; say g_s; g_s=sourceline(i); end
  324.       say
  325.       end
  326.     end
  327.       interpret Cparse(g_c,template,'args')
  328.       if args.ERRCODE > 1 then do; say args.ERRTEXT; exit 5; end
  329.  
  330.       /*
  331.  
  332.       This is the body of the program, that would actually do
  333.       something. From here on in the program, ARGS.FROM, ARGS.TO, and
  334.       ARGS.QUIET will contain the values from the command line.
  335.  
  336.       */
  337.  
  338.       exit 0
  339.       ---------------------------------------------------------------
  340.  
  341.     Or, of course, you can figure out your own way to use it.
  342.  
  343.     Example programs
  344.     ================
  345.  
  346.     I've included many example programs illustrating the above in
  347.     this release. The programs are also useful in their own right.
  348.  
  349.     Limits
  350.     ======
  351.  
  352.     Variable names (keywords in the template) are limited to 30
  353.     characters. Stem variable names should be reasonably short,
  354.     perhaps less than 8 characters. The returned string is limited
  355.     to 1023 characters. If this isn't long enough, I can change it.
  356.  
  357.  
  358.   =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  359.  
  360.   Fparse - parse a file name
  361.   ------
  362.  
  363.     Syntax
  364.     ======
  365.  
  366.     string = Fparse(start_dir,filespec,[defaultspec],
  367.             [relatedspec],[item])
  368.  
  369.  
  370.     start_dir is beginning directory. If I knew more about all this
  371.     stuff, this argument wouldn't be needed. We could find out the
  372.     current directory and use that. I accually tried that first but
  373.     it didn't seem to work (crashed). For now, just put
  374.     "pragma('D')" here when calling this routine.
  375.  
  376.     filespec is the name of the file you want. It can include a
  377.     volume name and/or directories, including leading /'s to move
  378.     up from the start_dir.
  379.  
  380.     defaultspec and relatedspec are optional parameters containing
  381.     all or parts of a filespec, and is supplied in the same form as
  382.     filespec. Any parts of the file name missing from filespec will
  383.     be supplied from defaultspec, then relatedspec.
  384.  
  385.     item is one of: 'Volume'          Volume:
  386.             'Directory'       dir/
  387.             'Name'            filename
  388.             'Type'            .type
  389.             'File'            filename.type
  390.             'c' (any
  391.              character)   Volume:<c>dir/<c>filename<c>.type
  392.             (null or
  393.              missing          Volume:[dir/]filename[.type]
  394.  
  395.     Description
  396.     ===========
  397.  
  398.     Given a partial filename (ie, "file.type" or "/over1/file"),
  399.     this function will return a string containing the complete
  400.     filename, or any or all parts of the filename. Defaults may be
  401.     supplied (for any of the categories volume, directory, name, or
  402.     type) in two optional arguments.
  403.  
  404.     Wildcard characters are left as found. No check is made for the
  405.     existence of any device or directory.
  406.  
  407.     If you want a spec ending in a directory, be sure and include a
  408.     trailing '/'. The start_dir parameter does not need one, as it
  409.     is assumed to be a directory, and the others aren't.
  410.  
  411.     Examples
  412.     ========
  413.  
  414.       say fparse(pragma('D'),'name','.type')  ==> Work:files/name.type
  415.       say fparse(pragma('D'),'/name','.type') ==> Work:name.type
  416.  
  417.  
  418.   =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  419.  
  420.  
  421.   Conditions for use and distribution
  422.   -----------------------------------
  423.  
  424.     RexxExtra is Copyright (c) 1990 by Dale W. Thompson
  425.  
  426.     RexxExtra is a copyrighted program that is provided "as is".
  427.     There is no warranty, either expressed or implied, as to the
  428.     quality or usefullness of the program. The user of the
  429.     program accepts all risks associated with it's use.
  430.  
  431.     RexxExtra is freely distributable provided:
  432.  
  433.     1. The files are included in their original form without
  434.        additions, deletions, or modifications of any kind.
  435.  
  436.     2. No charge is made for RexxExtra (other than a reasonable
  437.        copy charge of $6.00 or less).
  438.  
  439.     3. RexxExtra is not packaged as a part of a commercial
  440.        product.
  441.  
  442.     4. RexxExtra may not be uploaded to any electronic service
  443.        that claims a copyright to it's files and programs.
  444.  
  445.  
  446.   Requests for additional functions
  447.   ---------------------------------
  448.  
  449.     The author is always looking for candidate functions to add to
  450.     the library. If you have an idea for a function or, better yet,
  451.     if you have C source code for a function you would like to see
  452.     available from ARexx, send it to me and I'll try to include it
  453.     in the next release.
  454.  
  455.  
  456.   Author
  457.   ------
  458.  
  459.     This software was developed by Dale W. Thompson from an example
  460.     library supplied on the ARexx disk (version 1.10), by William
  461.     S. Hawes. All changes and additions by me. This library was
  462.     compiled with A68K, a public domain assembler, and Lattice C
  463.     V4.0.
  464.  
  465.     Any comments, questions, suggestions, flames, improvements, bug
  466.     reports (what bug? that's a feature.), etc., can be directed to
  467.     the following address:
  468.  
  469.      Dale W. Thompson
  470.      542 N. 95th Circle
  471.      Mesa, AZ  85207
  472.  
  473.     or you can leave me a message on one of the following boards:
  474.  
  475.      AmAzing Connection - Phoenix, AZ - (602) 843-6574
  476.  
  477.      Database 2000        - Phoenix, AZ - (602) 242-6734
  478.  
  479.  
  480.